<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>GroupAdd</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>GroupAdd</h1>

<p>Adds a window specification to a window group, creating the group if necessary.</p>

<pre class="Syntax">GroupAdd, GroupName [, WinTitle, WinText, Label, ExcludeTitle, ExcludeText]</pre>
<h3>Parameters</h3>
<dl>

  <dt>GroupName</dt>
  <dd><p>The name of the group to which to add this window specification. If the group doesn't exist, it will be created. Group names are not case sensitive.</p></dd>

  <dt>WinTitle</dt>
  <dd><p>A window title or other criteria identifying the target window. See <a href="../misc/WinTitle.htm">WinTitle</a>.</p></dd>

  <dt>WinText</dt>
  <dd><p>If present, this parameter must be a substring from a single text element of the target window (as revealed by the included Window Spy utility). Hidden text elements are detected if <a href="DetectHiddenText.htm">DetectHiddenText</a> is ON at the time that <a href="GroupActivate.htm">GroupActivate</a>, <a href="GroupDeactivate.htm">GroupDeactivate</a>, and <a href="GroupClose.htm">GroupClose</a> are used.</p></dd>

  <dt>Label</dt>
  <dd><p>The label of a subroutine to run if no windows matching this group (or this <i>window specification</i> prior to AHK_L 54) exist when the <a href="GroupActivate.htm">GroupActivate</a> command is used. The label is jumped to as though a <a href="Gosub.htm">Gosub</a> had been used. Omit or leave blank for none.</p></dd>

  <dt>ExcludeTitle</dt>
  <dd><p>Windows whose titles include this value will not be considered.</p></dd>

  <dt>ExcludeText</dt>
  <dd><p>Windows whose text include this value will not be considered.</p></dd>

</dl>

<h3>Remarks</h3>
<p>Each use of this command adds a new rule to a group. In other words,  a group consists of a set of criteria rather than a fixed list of windows. Later, when a group is used by a command such as <a href="GroupActivate.htm">GroupActivate</a>, each window on the desktop is checked against each of these criteria. If a window matches one of the criteria in the group, it is considered a match.</p>
<p>Although <a href="SetTitleMatchMode.htm">SetTitleMatchMode</a> and <a href="DetectHiddenWindows.htm">DetectHiddenWindows</a> do not directly affect the behavior of this command, they do affect the other group commands such as <a href="GroupActivate.htm">GroupActivate</a> and <a href="GroupClose.htm">GroupClose</a>. They also affect the use of ahk_group in any other command's <a href="../misc/WinTitle.htm">WinTitle</a>.</p>
<p>A window group is typically used to bind together a collection of related windows, which is useful for tasks that involve many related windows, or an application that owns many subwindows. For example, if you frequently work with many instances of a graphics program or text editor, you can use <a href="GroupActivate.htm">GroupActivate</a> on a hotkey to visit each instance of that program, one at a time, without having to use alt-tab or task bar buttons to locate them.</p>
<p>Since the entries in each group need to be added only once, this command is typically used in the auto-execute section (top part of the script). Attempts to add duplicate entries to a group are ignored.</p>
<p>To include <u>all</u> windows in a group (except the special Program Manager window), use this example:</p>
<pre>GroupAdd, AllWindows</pre>
<p>All windowing commands can operate upon a window group by specifying <code>ahk_group MyGroupName</code> for the <em>WinTitle</em> parameter. The commands <a href="WinMinimize.htm">WinMinimize</a>, <a href="WinMaximize.htm">WinMaximize</a>, <a href="WinRestore.htm">WinRestore</a>, <a href="WinHide.htm">WinHide</a>, <a href="WinShow.htm">WinShow</a>, <a href="WinClose.htm">WinClose</a>, and <a href="WinKill.htm">WinKill</a> will act upon <strong>all</strong> the group's windows. To instead act upon only the topmost window, follow this example:</p>
<pre>WinHide % &quot;ahk_id &quot; . WinExist(&quot;ahk_group <strong>MyGroup</strong>&quot;)</pre>
<p>By contrast, the other window commands such as <a href="WinActivate.htm">WinActivate</a> and <a href="WinExist.htm">IfWinExist</a> will operate only upon the topmost window of the group.</p>
<h3>Related</h3>
<p><a href="GroupActivate.htm">GroupActivate</a>, <a href="GroupDeactivate.htm">GroupDeactivate</a>, <a href="GroupClose.htm">GroupClose</a></p>
<h3>Examples</h3>
<pre class="NoIndent"><em>; In the autoexecute section at the top of the script:</em>
GroupAdd, MSIE, ahk_class IEFrame <em>; Add only Internet Explorer windows to this group.</em>
return <em>; End of autoexecute section.</em>

<em>; Assign a hotkey to activate this group, which traverses
; through all open MSIE windows, one at a time (i.e. each
; press of the hotkey).</em>
Numpad1::GroupActivate, MSIE, r

<em>; Here's a more complex group for MS Outlook 2002.
; In the autoexecute section at the top of the script:</em>
SetTitleMatchMode, 2 
GroupAdd, mail, Message - Microsoft Word <em>; This is for mails currently being composed</em>
GroupAdd, mail, - Message ( <em>; This is for already opened items 
; Need extra text to avoid activation of a phantom window:</em>
GroupAdd, mail, Advanced Find, Sear&amp;ch for the word(s)
GroupAdd, mail, , Recurrence: 
GroupAdd, mail, Reminder 
GroupAdd, mail, - Microsoft Outlook 
return  <em>; End of autoexecute section.</em>


Numpad5::GroupActivate, mail <em>; Assign a hotkey to visit each Outlook window, one at a time.</em></pre>

</body>
</html>
